/*
 * BLE模块头文件 - 包含API声明
 */

#ifndef BLE_MODULE_H
#define BLE_MODULE_H

#include "esp_err.h"
// 新增：通用类型
#include <stdint.h>
#include <stddef.h>

// 日志标签
#define BLE_MODULE_TAG "BLE_MODULE"

/**
 * @brief 初始化BLE模块
 * @return esp_err_t 初始化结果
 */
esp_err_t ble_init(void);

/**
 * @brief 更新并发送日历数据
 * @param data 日历数据缓冲区
 * @param length 数据长度
 * @return esp_err_t 操作结果
 */
esp_err_t ble_update_calendar_data(uint8_t *data, uint16_t length);

/**
 * @brief 获取当前控制数据
 * @param data 接收控制数据的缓冲区
 * @param length 数据长度
 * @return esp_err_t 操作结果
 */
esp_err_t ble_get_control_data(uint8_t *data, uint16_t *length);

/**
 * @brief 发送通用数据
 * @param data 数据缓冲区
 * @param data_len 数据长度
 * @return esp_err_t 操作结果
 */
esp_err_t ble_send_data(uint8_t *data, uint16_t data_len);

/**
 * @brief 发送通用数据（默认0xffff）
 * @return esp_err_t 操作结果
 */
esp_err_t ble_send_generic_data(void);

/**
 * @brief 获取当前采样间隔配置（功能已移除）
 * @param interval 采样间隔值（单位：毫秒）
 * @return esp_err_t 操作结果
 */
esp_err_t ble_get_sample_interval(uint32_t *interval);

/**
 * @brief 设置采样间隔配置（功能已移除）
 * @param interval 采样间隔值（单位：毫秒，范围：1000-600000ms）
 * @return esp_err_t 操作结果
 */
esp_err_t ble_set_sample_interval(uint32_t interval);

// ---------------- 新增：协议相关公共接口 ----------------
/**
 * @brief 是否有完整的大数据可读取（遵循设计文档3.3/3.5）
 * @return true 有完整数据；false 无
 */
bool ble_module_has_complete_data(void);

/**
 * @brief 读取完整数据到外部缓冲区
 * @param buffer 外部缓冲区指针
 * @param buffer_len 外部缓冲区长度
 * @return 实际写入的字节数（0表示无完整数据或缓冲区不足）
 */
size_t ble_module_get_complete_data(uint8_t *buffer, size_t buffer_len);

/**
 * @brief 注册时间同步回调（APP下发时间后触发）
 * @param cb 回调函数指针：参数为 utc_ms、tz_offset_min、flags（bit0=平滑校时）
 * @return esp_err_t 操作结果
 */
esp_err_t ble_register_time_sync_callback(void (*cb)(uint64_t utc_ms, int16_t tz_offset_min, uint8_t flags));

#endif /* BLE_MODULE_H */